home *** CD-ROM | disk | FTP | other *** search
/ Creative Computers / Creative Computers CD-ROM, Volume 1 (Legendary Design Technologies, Inc.)(1994).iso / shareware / telecom / xprzmodem_3.1 / xprzmodem.doc < prev    next >
Text File  |  1994-11-17  |  35KB  |  660 lines
  1.  
  2.                     Documentation for XPRZModem.library
  3.               This is Version 3.1, 3 Oct 1993, by Rainer Hess
  4.                                based on
  5.                Version 2.10, 12 February 1991, by Rick Huebner
  6.  
  7.  
  8. |---
  9. |           Update comments for XprZmodem.Library
  10. |    Version 2.50 Update, 15 November 1991, by William M. Perkins
  11. |    Version 2.51 bug fix, 29 January 1992, by John Tillema
  12. |    Version 2.52 recompiled, 6 March 1992, by William M. Perkins
  13. |     Proto additions for the SAS 5.10B Compiler by Jim Cooper
  14. |    Version 2.61 recompiled, 4 July 1993, by Rainer Hess
  15. |     Little Bugfix for SAS/C 6.x used SAS/6.3 also changed
  16. |     Funktion mysprintf() to xprsprinf() now written in Assembler
  17. |    Version 2.62 - Bulid in variable Blocksize
  18. |    Version 2.63 - Now localeized if you use WB2.1 or 3.x you can
  19. |     use this future. On this time will only a german catalog
  20. |     avaiable, default will be english or if you use a older
  21. |     Kickstart/Workbench.
  22. |    Version 2.64 - Bug fix in function update_rate(), save of GURU
  23. |     #80000005 on little files eg. 2 Bytes. Compiled Librarys for
  24. |     all prozessors (68000/010/020/030/040), for kick 1.x and
  25. |     up to 2.x, by Rainer Hess
  26. |    Version 3.0 - Now it's time, i think, to make a new version
  27. |     number, this will be a full release.
  28. |    Version 3.1, - Documentation update by Geoffrey Faivre-Malloy
  29. |      Conversion of documentation to Amigaguide format.
  30. |     Code-Changes by Rainer Hess:
  31. |     ZModem runs always with the sender blocksize or uses standart-mode
  32. |     (M1024) if there is on one system a older zmodem.
  33. |---
  34.  
  35. |---
  36. |    All of my additions to this documentation are indicated by
  37. |  <--  this left margin braketing.   -WMP-
  38. |---
  39.  
  40. 1.  Introduction (or "What is this thing, anyway?")
  41. ---------------------------------------------------
  42.  
  43.      XPRZModem.library  is  an  Amiga  shared  library (with full Lattice C
  44. source  code)  which  provides  ZModem  file  transfer  capability  to  any
  45. XPR-compatible  communications program.  The XPR external protocol standard
  46. describes  an interface method which allows various file transfer protocols
  47. to  be  implemented  as  Amiga  shared  libraries  which  may  then be used
  48. interchangeably  in  any  compatible  communications program.  This takes a
  49. heavy  load  off  of  the comm program author, who no longer has to support
  50. scads  of different file transfer protocols (many of which are quite tricky
  51. to  code)  in  their program in order to make it widely useful and popular.
  52. The  comm program is also smaller and more efficient as a result, since all
  53. those obscure protocols (you know, the ones *you* don't need) are no longer
  54. taking  up space.  The XPR standard also helps users, who can mix and match
  55. their  favorite  file transfer protocols (and implementations thereof) with
  56. their  favorite  comm  programs.   And when new protocols are invented, the
  57. user  simply  plugs  in  a  new  library,  and  voila!,  it's ready to use.
  58. Hopefully, making protocols easy to support will allow more and better comm
  59. programs  to  be  written,  as  authors  can  concentrate on their programs
  60. instead of constantly re-inventing the wheel.
  61.  
  62.      Of  course,  for all of this wonderful stuff to happen, there needs to
  63. be  a  good  selection  of  these  XPR  protocol libraries available to the
  64. public.   It's  the  classic  chicken-and-egg problem; comm program authors
  65. won't  be  motivated  to support the XPR standard unless there are a goodly
  66. number  of  protocols  available  for  it.   And other programmers won't be
  67. motivated  to  write XPR protocol libraries until there are a goodly number
  68. of comm programs which can use them.  In an effort to do my bit [ B^) ] for
  69. the Amiga community, which has given me so many neat toys to play with over
  70. the past few years, I decided to try and help get the ball rolling.
  71.  
  72.      Hopefully,  the  early  availability  of  a  ZModem  library will help
  73. stimulate interest in the XPR standard, resulting in better Amiga telecomms
  74. for  all  of  us.   And  by making my source code PD, I hope to help others
  75. interested  in  writing  XPR protocol libraries by giving them some serious
  76. example  code.   Also, having ZModem library code readily available to John
  77. Q.   Hacker  should help ensure a steady stream of new lemon-fresh enhanced
  78. ZModem libraries (with enzymes) for all of us to use in the future.
  79.  
  80.      Of course, no discussion of the XPR standard would be complete without
  81. giving  proper credit to the author, Willy Langeveld of the Stanford Linear
  82. Accelerator  Center.  Many thanks are due him for this effort.  If you have
  83. any  further  questions  about  the  XPR standard, be sure and download the
  84. spec;  it should be available on BIX (since he's a sysop there), or on most
  85. other major systems.  And I'll try to keep the current version available on
  86. my BBS, as well.
  87.  
  88.      All  files  in  this  archive  which  are  not  copyrighted are hereby
  89. released  to the public domain (which they were anyway, by way of not being
  90. copyrighted,  but  I  want  to make sure YOU realize that).  Do as you like
  91. with  them.   Please  make  lots of copies and distribute them all over the
  92. place,  and  make  lots of derivative works, and everything!  Heck, you can
  93. even publicly perform and/or display this code if you can figure out how...
  94.  
  95.  
  96.  
  97. 2.  Installation (OK, enough chatter; let's get to work)
  98. --------------------------------------------------------
  99.  
  100.      Couldn't  be  easier.   Just copy the xprzmodem.library file into your
  101. LIBS:   directory.   All  XPR-compatible comm programs should provide a way
  102. for  you to select which XPR protocol you wish to use, either by giving you
  103. a  file  requester showing LIBS:xpr*.library, or by automatically detecting
  104. these libraries and adding them into their menus.
  105.  
  106. WARNING:   Versions  of  VLT  prior  to  revision  4.107  had  a bug in the
  107. xpr_sflush()  routine  which  caused random Guru 3 crashes on some systems.
  108. If  you're using a version of VLT older than 4.107, it would be a good idea
  109. to  upgrade  to  the  latest rev.  Besides, there's a bunch of new features
  110. you're missing, anyway...
  111.  
  112. ANOTHER  WARNING:   Versions  of  VLT  prior  to  5.034  had  a  bug in the
  113. xpr_sread()  function  which  caused  them  to (at least sometimes) fail to
  114. return  any bytes received so far when an xpr_sread() call timed out.  This
  115. version  of  XPRZModem.library  requires VLT version 5.034 or later.  (Yes,
  116. Willy, it really was broken B-))
  117.  
  118. |---
  119. |    XprZmodem.Library version 2.50 and 2.52 tested with WTerm version
  120. |    0.82 and Willy's term program, VLT version 5.045.  No problems
  121. |    occurred.  It should work fine with any term program that was able
  122. |    to work with the version 2.10 of XprZmodem.Library.    -WMP-
  123. |---
  124.  
  125. 3.  Options
  126. -----------
  127.  
  128.      The  XPR  standard  lays  out  two  ways  for the comm program user to
  129. specify options for the XPR protocol.  The more primitive option is for the
  130. comm  program  to  provide  a method of passing an option string to the XPR
  131. library  before  transferring  files.  The precise format and usage of this
  132. option  string is left up to the XPR protocol author; the comm program just
  133. sends  it verbatim.  If an environment variable is found with the same name
  134. as  the  XPR  protocol  (i.e.  there's a file in the ENV:  directory called
  135. "xprzmodem"),  the comm program is supposed to use this string (contents of
  136. file) to initialize the protocol options.  Also, a menu option or some such
  137. should  normally  be  provided which will allow the user to be prompted for
  138. the option string interactively.
  139.  
  140.      Version  2.0 of the XPR standard created a new, more sophisticated way
  141. for  the  comm  program  user  to specify XPR options.  If the comm program
  142. supports  it,  the  XPR  library can give the comm program a list of option
  143. prompts,  and  the comm program can then let the user interactively set the
  144. various options individually, possibly even using nice gadgets and stuff.
  145.  
  146.      In  any  case,  no  matter how your particular comm program feels like
  147. handling  it,  these  are  the  options supported by this implementation of
  148. ZModem:
  149.  
  150.           T{Y|N|?|C}   Text translation mode:
  151.              TY = Text Yes; if receiving, translate CR/LF pairs or solo
  152.                   CR chars to normal Amiga LF chars.  Ignore d